/**
 * @file    bundles.h
 * @brief   Documentation: WOSH Bundles
 ****************************************************************************
 * @author  Alessandro Polo
 * @version 0.8.384 $Id: bundles.h 2861 2010-08-07 02:42:53Z alex $
 ****************************************************************************/
/* Copyright (c) 2007-2010, WOSH - Wide Open Smart Home 
 * by Alessandro Polo - OpenSmartHome.com
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the OpenSmartHome.com WOSH nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY Alessandro Polo ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL Alessandro Polo BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ****************************************************************************/
 
/*! \page page_bundles Bundles
 *
 * This page introduces the generic WOSH service, called \b "Bundle".
 *
 * It is suggested to read \ref page_core "WOSH Core documentation" first.
 *
 * \section page_bundles_toc Table of Contents:
 *
 *  - \ref page_bundles_overview
 *
 *  - \ref wosh::Bundle (wosh::BundleGeneric)
 *
 *  - Implementations are listed in modules \ref Services, \ref Devices.
 *
 *
 * "An agent is anything that can be viewed as perceiving its environment
 * through sensors and acting upon that environment through effectors."
 * \c (Russel & Norving, 1995)
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_bundles_overview Overview
 *
 * wosh::Bundle is the base class of most 'real' component of WOSH system.
 *
 * Bundles may be compared to services on Windows and daemons on POSIX,
 * but a \c Bundle may be compared to a generic application for many aspects.
 * The class-name was inspired by Java and OsGi standards.
 *
 * Bundles may (and usually do):
 *  - interact with other Bundles and (system) events
 *  - hold and monitor properties
 *  - implement specific interface and methods
 *  - provide various functionalities
 *  - fork processes (threads)
 *
 * As any software component, a Bundle may have any requirements (dependencies relative to its state).
 * 
 * wosh::BundleManager is the core-module designed to manage life-cycle of bundles,
 * its loading, state-transitions and requirement-validation.
 *
 * As you should know, WOSH is a message-oriented distributed system, bundles as other components
 * interact and cooperate using wosh::Message: listening and posting messages to wosh::Bus.
 *
 * Bundles implement a well known interface (wosh::Bundle, hard-coded: standard C++ abstract class)
 * and support a set of common methods (wosh::MethodsProvider): wosh::Method (custom binding for messaging transparency).
 *
 * Bundles supports a set of wosh::Property (name, value, permission), the system and under-lying components
 * as wosh::PropertiesProvider allow access/role control and monitoring with few lines of code.
 *
 * A generic bundle supports a set of interfaces, in other words: claim to support some specific services
 * using a well-known protocol. Often interface-identification is used within message's target expression,
 * user neither developer should care much since definition and evaluation are performed
 * by wosh::InterfaceProvider component.
 *
 * As said, bundles may have various requirements. They are configured (usually hard-coded) and stored in
 * wosh::BundleRequirements component.
 *
 * See wosh::Bundle for more technical information.
 *
 * Since wosh::Bundle is a pure abstract class, wosh::BundleGeneric object is provided in order to reduce
 * shared code in generic implementation, actually all bundles inherit this class. 
 *
 *
 * As any WOSH object, bundles are identified and dynamically created
 * by the \ref page_core_objectfactory "WOSH Object-Allocation model".
 *
 * Configuration and loading process is described in \ref page_config "WOSH Configuration".
 *
 * (Bundle) Interfaces are defined in <a href="../../src/interfaces">/src/interfaces</a> folder
 * within namespace wosh::interfaces.
 *
 * Bundles (sources) are located in <a href="../../src/bundles">/src/bundles</a> folder.
 *
 *
 * \see Services
 * \see Devices
 * 
 * \see wosh::interfaces::IBundle
 * \see wosh::BundleManager
 * \see wosh::BundleGeneric
 * \see wosh::BundleRequirements
 *
 *
 ****************************************************************************
 *
 */
